home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 February: Tool Chest / Dev.CD Feb 00 TC.toast / pc / what's new? / sample code / human interface toolbox / packagetool / sample package / htmlsample sources / history.h < prev    next >
Encoding:
C/C++ Source or Header  |  1999-12-02  |  4.5 KB  |  133 lines
  1. /*
  2.     file History.h
  3.     
  4.     Description:
  5.     This file contains routine prototypes and type declarations that can
  6.     be used to access the routines defined in History.c  These routines
  7.     are used to store visitled links.
  8.     
  9.     HTMLSample is an application illustrating how to use the new
  10.     HTMLRenderingLib services found in Mac OS 9. HTMLRenderingLib
  11.     is Apple's light-weight HTML rendering engine capable of
  12.     displaying HTML files.
  13.  
  14.     Copyright: © 1999 by Apple Computer, Inc.
  15.     all rights reserved.
  16.     
  17.     Disclaimer:
  18.     You may incorporate this sample code into your applications without
  19.     restriction, though the sample code has been provided "AS IS" and the
  20.     responsibility for its operation is 100% yours.  However, what you are
  21.     not permitted to do is to redistribute the source as "DSC Sample Code"
  22.     after having made changes. If you're going to re-distribute the source,
  23.     we require that you make it clear in the source that the code was
  24.     descended from Apple Sample Code, but that you've made changes.
  25.     
  26.     Change History (most recent first):
  27.     10/16/99 created
  28. */
  29.  
  30.  
  31. #ifndef __HISTORY__
  32. #define __HISTORY__
  33.  
  34. #include <Types.h>
  35. #include <Menus.h>
  36.  
  37.  
  38. /* HistoryDataHandle defines the data type we are using
  39.     for storing historical information about visited links.
  40.     A history is maintained as a list/stack where we can
  41.     move backwards and forwards referencing elements as
  42.     required.  The only difference between a history and
  43.     a stack is that if we add a new element to the history,
  44.     then all elements beyond the current reference are
  45.     deleted before the new element is added. */
  46. typedef struct HistoryData HistoryData;
  47. typedef HistoryData *HistoryDataPtr, **HistoryDataHandle;
  48.  
  49.  
  50. /* NewHistory creats a new history and returns
  51.     a handle to it. */
  52. HistoryDataHandle NewHistory(void);
  53.  
  54.  
  55. /* DisposeHistory disposes of a history and all of the
  56.     structures allocated for it. */
  57. void DisposeHistory(HistoryDataHandle hd);
  58.  
  59.  
  60. /* AddToHistory adds a new element to the history.  Both
  61.     the URL and the printed representation of its url
  62.     are stored.  NOTE:  if we have called GoBack a few times
  63.     before this call, then those previously viewed items
  64.     are removed from the history. This is so if we choose
  65.     GoBack again, then we will arrive at the same link we
  66.     are looking at now.  */
  67. OSErr AddToHistory(HistoryDataHandle hd, char const* url, StringPtr printName);
  68.  
  69.  
  70. /* InHistory returns true if the URL is among the urls
  71.     currently stored in the history. */
  72. Boolean InHistory(HistoryDataHandle hd, char const* url);
  73.  
  74. /* CanGoBack returns true if it makes sense to call the
  75.     GoBack command.  i.e. if there are one or more links
  76.     in the history beyond the current one. */
  77. Boolean CanGoBack(HistoryDataHandle hd);
  78.  
  79. /* GoBack copies the previous url in the history
  80.     into a new handle and returns that handle in
  81.     *url.  It is the caller's responsibility to dispose
  82.     of the handle after it has been used. */
  83. OSErr GoBack(HistoryDataHandle hd, Handle *url);
  84.  
  85.  
  86. /* CanGoForward returns true if it makes sense to call the
  87.     GoForward command.  i.e. if there are one or more links
  88.     in the history ahead of the current one.  This can only
  89.     happen after the user has chosen GoBack one or more
  90.     times. */
  91. Boolean CanGoForward(HistoryDataHandle hd);
  92.  
  93.  
  94. /* GoForward copies the next url in the history
  95.     into a new handle and returns that handle in
  96.     *url.  It is the caller's responsibility to dispose
  97.     of the handle after it has been used. */
  98. OSErr GoForward(HistoryDataHandle hd, Handle *url);
  99.  
  100.  
  101. /* CanGoHome returns true if it makes sense to call the
  102.     GoHome command.  i.e. if there are one or more links
  103.     in the history.  This can only happen after AddToHistory
  104.     has been called one or more times. */
  105. Boolean CanGoHome(HistoryDataHandle hd);
  106.  
  107.  
  108. /* GoBack copies the first url in the history
  109.     into a new handle and returns that handle in
  110.     *url.  It is the caller's responsibility to dispose
  111.     of the handle after it has been used. */
  112. OSErr GoHome(HistoryDataHandle hd, Handle *url);
  113.  
  114.  
  115. /* AppendHistoryToMenu rebuilds the Go menu adding items to the
  116.     bottom of the menu according to the items in the
  117.     history.  The names of the items are the same as
  118.     the printNames provided in the AddToHistory command. */
  119. OSErr AppendHistoryToMenu(HistoryDataHandle hd, MenuHandle theMenu);
  120.  
  121.  
  122. /* GoToMenuItem copies the itemIndex'th url in the history
  123.     into a new handle and returns that handle in
  124.     *url.  It is the caller's responsibility to dispose
  125.     of the handle after it has been used.  This routine
  126.     should only be called after a menu selection has
  127.     been made in a menu built by AppendHistoryToMenu.  */
  128. OSErr GoToMenuItem(HistoryDataHandle hd, Handle *url, short itemIndex);
  129.  
  130.  
  131. #endif
  132.  
  133.